/*
 * Copyright 2009 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
package org.splink.deepsplink.page {
	import org.splink.library.IFinalizable;
	/**
	 * Implement the <code>IPage</code> and the <code>IPageSupplier</code>
	 * interface in order to act as a deepsplink page. There is also a 
	 * conventience base class called <code>Page</code>.
	 *
	 * Upon framework initialization each <code>IPage</code> 
	 * implementation is instantiated which is decalared to deepsplink either through a 
	 * <code>IPageFactoryTemplate<code> implementation or the clazz attribute
	 * within the config.dtd based xml which is loaded at startup. 
	 * 
	 * If you are using xml configuration, you need to make sure your page class is
	 * compiled into the swf. This can be done via compiler options, or just placing
	 * a reference to your page class into the application main class. 
	 * 
	 * @see org.splink.deepsplink.page.Page
	 * @author Max Kugland
	 */
	public interface IPage extends IFinalizable {
		
		/**
		 * Is invoked when the page parameters have changed. Upon page initialization
		 * <code>onParamsChanged</code> is not invoked, but if parameters are present
		 * they are available through <code>IPageSupplier</code>'s <code>getParams</code> 
		 * or <code>getParamValueForKey</code> method.
		 * 
		 * @param params an array of <code>PageParameter</code> instances
		 * @see org.splink.deepsplink.page.IPageSupplier
		 */
		function onParamsChanged(params : Array) : void;
		
		/**
		 * Initializes the page. At initialization time the page display is part
		 * of the displaylist. Upon page initalization completion you need to
		 * invoke <code>IPageSupplier</code>'s <code>initialized</code> method.
		 * 
		 * If parameters are present they are available through 
		 * <code>IPageSupplier</code>'s <code>getParams</code> or 
		 * <code>getParamValueForKey</code> method.
		 * 
		 * @see org.splink.deepsplink.page.IPageSupplier
		 */
		function initialize() : void;
		
		/**
		 * @return the id of the page
		 */
		function get id() : String;
	}
}
